When OIT staff create an account for a user on hpc, certain things are set by default and a certain directory structure created. The purpose of this page is to explicitly list and explain the defaults and particularly to describe and discuss the details of the default directory structure. This discussion should be very useful to understand the ideas behind the setup that was planned with great care collaboratively by the user committee and OIT staff. If you have feedback, suggestions, or questions, do not hesitate to contact the chair of the user committee please.

Table of Contents

Hostname, operating system, shell, and miscellaneous

The only node with a connection to the outside network is the user node; internally to the system, its full hostname is hpc.cl.rs.umbc.edu (notice the "cl"), but from the outside, its name is hpc.rs.umbc.edu. To log in to the system, you must use a secure shell like ssh from Unix/Linux, PuTTY from Windows, or similar. From anywhere on the internet, a call to ssh under Linux would look like

ssh username@hpc.rs.umbc.edu

where username is your UMBC username (that you use in myUMBC and that is the base part of your UMBC e-mail address). Your password is your myUMBC password. If your username on your client system is the same as on hpc, you can just say "ssh hpc.rs.umbc.edu", and from within UMBC, you can actually just say "ssh hpc.rs". See also the man page for ssh, "man ssh", for more general information. If you intend to make plots with Matlab or IDL (or do some other graphical work) then you will need to enable X11 forwarding. Usually that is done by adding a -Y flag to your ssh command:

ssh -Y username@hpc.rs.umbc.edu

If you have an old enough version of ssh, you may have to use -X instead of -Y. Ideally, you should always use -X since it provides improved security, but it breaks many applications (including Matlab) so using it is usually not possible.

HPC runs the standard UMBC distribution of the Linux operating system, RedHat Enterprise License 5. We chose the bash as the default shell for users; this will be the shell that you are assumed to be in for purposes of documentation and examples on this webpage; check your shell by saying "echo $SHELL" or by saying "env" and searching for SHELL in the resulting lines of output.

Storage Areas and Directory Structure

The directory structure that OIT will set up as part of your account creation is designed to facilitate the work of research groups consisting of several users and also reflects the fact that all accounts on hpc must be sponsored by a faculty member at UMBC. This sponsor will be referred to as PI (for principal investigator) in the following.

To give a concrete example, let us assume that you are a student with username "username", who works in the research group of a PI with username "bossname", who sponsors the account. I assume now that the account for the PI has already been created and discuss the example from the standpoint of a new account for the student username being created. OIT will create three areas:

• home directory /home/username – this is where you start when you log in to HPC.
• personal scratch space /home/username/scratch/ – a large storage area for your temporary scratch files
• group common space /home/username/common/ – a large storage space shared between members of your research group. This is also intended to be used as temporary storage space. In some research groups, anyone in your group can create or delete files in the common space. In other research groups, only your PI can create or delete files there. That is configurable by your PI. Instructions for configuring that are below.
• UMBC research data storage space – this is slower, but more reliable storage that can be purchased from OIT. This storage area is accessible from anywhere in UMBC, unlike the scratch and common directories which can only be accessed from HPC.
• AFS /afs/umbc.edu/users/u/s/username – another UMBC-wide file storage area that is thoroughly backed up. This is the storage area where your UMBC email and webpage are stored, as well as your personal files for UMBC lab machines and gl.umbc.edu login servers. The /u/s in the directory name should be replaced with the first two letters of your username (ie: straha1 would be /s/t).

Some research groups have additional storage areas. To find out if you have UMBC research data storage space or other storage space, contact your PI or user support. The tutorial below will show you how to access your home directory, personal scratch space and group common space. For information about other storage areas, or to learn about how your data is stored, see this page: Disk Space and File Quotas.

Tutorial

Home Directory

Now let's explore these storage areas via a simple tutorial. This tutorial assumes you are a member of a research group. If you are not, then you will have no group scratch space and so those parts of this tutorial will not apply.

First, log in to HPC from your local machine via ssh:

me@mymachine:~> ssh username@hpc.rs.umbc.edu
Password: (type your password)
Last login: Wed Nov 01 at 04:03:21 2008 from mymachine.umbc.edu
Welcome to hpc.rs.umbc.edu:

A weekly hpc.rs cluster maintenance window is reserved for 
Tuesdays from 6-9pm EST. When downtime is needed, cluster users 
will be notified via the oit-hpc-users list (email) 5 days in 
advance, otherwise services will continue uninterrupted.

******************************************************************
* Questions or issues with hpc.rs.umbc.edu should be sent to     *
* [Old contact info removed]. Please include as much detail about* 
* your issue as possible.                                        *
******************************************************************


username@hpc:~$ _

At any given time, the directory that you are currently in is referred to as your current working directory. Since you just logged in, your home directory is your current working directory. The ~ represents in the command line (username@hpc:~$) – a ~ is shorthand for your home directory. The program pwd tells you the full path of the current working directory, so let's run pwd to see where your home directory really is:

username@hpc:~$ pwd
/home/username

Now let's use ls to get more information about your home directory.

username@hpc:~$ ls -ld ~
drwx------ 23 username pi_bossname 4096 Oct 29 22:35 /home/username

The -ld does two things: the l tells ls to use its long output format, and the d tells it to list information about the directory ~ instead of listing the contents of that directory. (Without the d, ls would list the files in your home directory, but not tell us about your home directory itself.)

As for the output of ls:

• d – the d at the beginning of the line tells you that ~ is a directory
• rwx – this tells you that you can read (r), write (w) and execute (x) ~. For directories, reading the directory means listing its contents, writing the directory means creating new files. To cd into a directory, you need execute permission. Execute permission is required for a number of more obscure things as well. When you use ls -l on a file (rather than a directory), read, write and execute permissions have the obvious meanings.
• ------ – these tell you that members of your research group (first three -'s) cannot read, write or execute ~, and other people (last three -'s) cannot read write or execute ~. If they could read, write or execute, you would see a r, w or x instead of a -
• username – this tells you that user username owns the directory.
• pi_bossname – this tells you the directory is also owned by the group pi_bossname.
• 4096 – this tells you how much space the directory takes on disk (in bytes). That space does not include the amount of space taken up by the files stored in the directory.
• Oct 29 22:35 – this is the last time the directory was modified.
• /home/username – this is the path to ~.

There is a lot of information there, but thankfully you don't have to care about much of it. All you really need to take out of this is that your home directory is /home/username and is accessible by the shorthand ~, and only you can create or view files in your home directory. Unfortunately, you have limited space available in your home directory, and you can see that by running the program quota:

username@hpc:~$ quota
Disk quotas for user username (uid 12345): 
     Filesystem  blocks   quota   limit   grace   files   quota   limit   grace
/dev/mapper/homevg-homelv
                  21532  100000  150000            1604   10000   15000        

These numbers tell you how much space you're using and how much is available. See our Disk Space and File Quotas page for more information about interpreting those numbers. You are only allowed to create up to 10,000 files that take up a total of 100,000 kB of storage space. That isn't much space and so you need to store some of your data in your scratch and common storage areas.

Group Common Storage Area

Let's look at those areas by running this command:

username@hpc:~$ ls -l
lrwxrwxrwx 1 username pi_bossname 33 Jul 29 15:48 common -> /thumper1/scratch/bossname/common
lrwxrwxrwx 1 username pi_bossname 40 Jul 29 15:48 scratch -> /thumper1/scratch/bossname/users/username

This time we're telling ls to list information about files in your home directory (since we left out the d in -ld this time). You may see additional files or directories listed if there are already other files or directories in your home directory. The lines output by ls tell us about scratch and common. The l at the beginning of each line tells you that scratch and common are actually symbolic links. The -> /thumper1/scratch/bossname/common tells you where the symbolic link links to. A symbolic link is a way of telling the operating system, "whenever someone accesses ~/common, send them to /thumper1/scratch/bossname/common instead." The common symbolic link links to your group scratch area and the scratch symbolic link links to your personal scratch area. Let's look at each of those. We'll start with common:

username@hpc:~$ ls -ld /thumper1/scratch/bossname/common
drwxrwsr-x 2 bossname pi_bossname 2 Jul 29 14:56 /thumper1/scratch/bossname/common

Some users may see this instead:

drwxr-sr-x 2 bossname pi_bossname 2 Jul 29 14:56 /thumper1/scratch/bossname/common

Note the r-s instead of rws. The permissions on common are different than the permissions on your home directory:

• first rwx – this means the owner of this directory (bossname) can list files in the directory (r), create files in the directory (w) or cd to the directory (x)
• rws or r-s – The r means anyone in the pi_bossname group can list the contents of the directory. The w if it is present means anyone in the pi_bossname group can create or delete files in the directory. Note that the third letter is an s instead of an x. The s means the Set GID bit is set and that means any files that anyone puts in this directory will have their group changed to pi_bossname. That way, if someone in another research group adds a file to your group's common scratch area, it will be owned by your group and so people in your group will be able to read or write it.
• last r-x – this means that users outside of your group can list the contents of the directory and cd to the directory.

Again, there is a lot of information there. All you need to remember is that you can create files in the common directory if the permissions say rwxrwsr-x. If they say rwxr-sr-x then only the PI (bossname) can create or delete files.

Configuring Permissions of the Group Common Storage Area (PI Only)

If you are a PI, you can add or remove the group write permissions (the w in r-s/rws) by using the chmod command. To add group write permissions (the w) and let all members of your group create or delete files and directories in your groups common directory:

bossname@hpc:~$ chmod g+w ~/common/

To remove group write permissions so that only you, the PI bossname, can create or delete files in your group's common directory:

bossname@hpc:~$ chmod g-w ~/common/

You could, of course, use the full path to ~/common/ in those commands: /thumper1/scratch/bossname/common.

Personal Scratch Area

Now lets look at your personal scratch area.

username@hpc:~$ ls -ld /thumper1/scratch/bossname/users/username
drwxr-sr-x 3 username pi_bossname 3 Sep 21 21:59 /thumper1/scratch/bossname/users/username

Since the permissions are drwxr-sr-x, only the owner of the directory (you: username) can create or delete files in that directory, but anyone in the group (your research group pi_bossname) can list the contents of the directory or cd to it.

The full path to your scratch and common directories might not be /thumper1/scratch/bossname/users/username and /thumper1/scratch/bossname/common. If you have no PI sponsoring you (such as if you are on HPC for a class), your personal scratch space is /thumper1/scratch/general/users/username and you have no common group scratch space.

How to Create Simple Files and Directories

Now let's try creating some files and directories. First, let's make a directory named "testdir" in your home directory:

username@hpc:~$ mkdir testdir
username@hpc:~$ ls -ld testdir
drwxr-x--- 2 username pi_bossname 4096 Oct 30 00:12 testdir
username@hpc:~$ cd testdir
username@hpc:~/testdir$ _

The mkdir command created the directory testdir. Since your current working directory was ~ when you ran that command, testdir is inside your home directory. Thus it is said to be a subdirectory of ~. The cd command changed your working directory to ~/testdir and that is reflected by the new prompt: username@hpc:~/testdir$. Now lets create a file in testdir:

username@hpc:~/testdir$ echo HELLO WORLD > testfile
straha1@hpc:~/testdir$ ls -l testfile
-rw-r----- 1 username pi_groupname 12 Oct 30 00:16 testfile
username@hpc:~/testdir$ cat testfile
HELLO WORLD
username@hpc:~/testdir$ cat ~/testdir/testfile
HELLO WORLD
username@hpc:~/testdir$ _

The echo command simply prints out its arguments ("HELLO WORLD"). The "\>" tells your shell to send the output of echo into the file testfile. Since your current working directory is ~/testdir, testfile was created in testdir and its full path is then ~/testdir/testfile. The program cat prints out the contents of a file (where the argument to cat, testfile or ~/testdir/testfile is the file to print out). As you can see, testfile does indeed contain "HELLO WORLD". Now let's delete testdir and testfile. You cannot delete a directory if it contains files, so we must delete testfile first:

straha1@hpc:~/testdir$ rm -i testfile
rm: remove regular file `testfile'? y

Now we delete the testdir directory:

straha1@hpc:~/testdir$ cd ~
straha1@hpc:~$ rmdir testdir